视频设备业务接口

一、应用场景

视频设备业务接口是物联网平台提供用于客户对视频设备进行业务操作的API。开发者可以使用视频设备业务相关接口，进行查询视频设备列表以及编辑设备等业务操作。开发者此类接口可实现如下业务场景：

开发者通过API查询视频设备列表的数据，获取全量的设备信息；
开发者通过API可以编辑维护视频设备列表的属性值
开发者可以通过API导出视频设备列表
开发者可以通过API往视频设备列表添加设备
开发者可以通过API导入视频设备列表
开发者可以通过API将物联网平台中已授权的设备，关联到视频设备列表中
开发者可以通过API删除视频设备列表的视频设备

二、功能说明

客户在物联网平台管理台【设备中心】配置后，可以在物联网平台管理台的设备中心中接入视频设备。从而通过调用以下文档提供的API接口，来实现使用对视频设备的查询、新增、删除、编辑、导入、导出等功能。

设备业务接口主要包含以下几种：

查询设备列表
新增视频设备
删除视频设备
编辑视频设备
导入视频设备
导出视频设备

三、前提条件

参考管理台设备部署手册《视频设备部署操作手册》，确保在管理台【设备中心】中完成对设备的接入上线；
设备已经配置到项目上。
如果是阿里IOT来源的设备，需要配置对应的appKey与appSecret。详情请看

四、关键流程

无

五、API列表

1、视频设备业务接口

1.1、设备列表

接口描述

应用于对视频设备列表的查询

请求方式

POST

请求地址

/v3/service/video-surveillance/projects/devices

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

body请求参数

名称	必填	类型	备注
offset	true	int	开始页码
limit	true	int	页大小
order	false	Object	排序条件
query	false	Object	过滤条件

请求示例：

{
    "offset": 0,
    "limit": 50,
    "order": {
        "create_time": "desc"
    },
    "query":{
    	"project_id":{
    		"$eq":"项目ID"
    	}
    }
}

返回参数说明

名称	必填	类型	备注
code	true	String	错误码
data	false	Object	数据
data.list	false	List	数据集
data.list.id	true	String	设备ID
data.list.address	true	String	设备安装位置
data.list.allow_shared	true	String	是否可以分享设备信息
data.list.area_name	true	String	区域名称
data.list.association_space_id	true	String	关联的空间ID
data.list.brand	true	String	设备品牌
data.list.building_name	true	String	楼栋名称
data.list.camera_resolution_ratio	true	String	摄像头分辨率
data.list.camera_type	true	Integer	摄像头类型: 1：普通摄像机（默认）；2：人脸分析机；3：行为分析机； 4：鹰眼摄像机； 5：球机；6：枪机
data.list.camera_type_name	true	String	摄像头名字
data.list.device_code	true	String	设备编码
data.list.device_id	true	Integer	设备ID
data.list.device_model	true	String	设备型号
data.list.device_type	true	String	设备类型
data.list.external_id	true	String	主数据设备ID
data.list.focus	true	Boolean	是否重点关注设备
data.list.group_id	true	String	设备分组ID
data.list.group_name	true	String	设备分组名称
data.list.house_name	true	String	房屋名称
data.list.install_address	true	String	安装位置
data.list.is_exception	true	Boolean	设备是否异常
data.list.is_online	true	Boolean	设备是否上线
data.list.mac	true	String	设备mac
data.list.maintenance_provider	true	String	设备维保单位
data.list.maintenance_provider_linkman	true	String	维保联系人名称
data.list.maintenance_provider_phone	true	String	维保联系人电话
data.list.name	true	String	设备名称
data.list.person_in_charge	true	String	设备负责人
data.list.product_id	true	String	产品ID
data.list.product_name	true	String	产品名称
data.list.production_data	true	String	出厂日期
data.list.project_id	true	String	项目ID
data.list.ptz_control	true	Boolean	是否支持云台控制
data.list.run_status	true	Boolean	运行状态
data.list.scene_id	true	List	场景ID
data.list.scene_name	true	List	场景名称
data.list.scrap_data	true	String	设备报废日期
data.list.sn	true	String	设备SN
data.list.source_system	true	String	设备来源
data.list.space_group_ids	true	List	空间分组ID
data.list.space_group_names	true	List	空间分组名称
data.list.space_id	true	String	空间ID
data.list.space_location	true	String	空间位置
data.list.space_name	true	String	空间名称
data.list.status	true	String	设备状态
data.list.supplier	true	String	设备供应商
data.list.unit_name	true	String	单元名称
msg	true	String	错误信息
status	true	integer	响应状态码

返回示例：

{
	"response_time": "2021-10-14T09:09:27.206Z",
	"code": "000000",
	"status": "200",
	"msg": "请求成功",
	"data": {
		"list": [{
			"product_id": "16059ec29839200916059ec29839b201",
			"product_name": "视频产品20210923",
			"device_code": "",
			"name": "公司大门",
			"brand": "",
			"mac": "849A40620D0F07",
			"sn": "",
			"install_address": "",
			"address": "",
			"space_id": null,
			"space_name": null,
			"supplier": "",
			"maintenance_provider": "",
			"maintenance_provider_linkman": "",
			"maintenance_provider_phone": "",
			"person_in_charge": "",
			"production_data": "",
			"scrap_data": "",
			"external_id": "",
			"space_location": "海南省琼中黎族苗族自治县什运乡170乡道",
			"space_group_names": null,
			"space_group_ids": null,
			"status": "0",
			"id": 619614334,
			"group_name": "重点关注设备,车行视频监控",
			"group_id": null,
			"project_id": "04044c2b566766e0c0669017fdc9aa21",
			"camera_type": 3,
			"camera_type_name": "人脸识别",
			"camera_resolution_ratio": "",
			"ptz_control": false,
			"area_name": "东区",
			"building_name": null,
			"unit_name": null,
			"house_name": null,
			"source_system": "video_surveillance",
			"device_type": null,
			"is_online": false,
			"run_status": false,
			"is_exception": false,
			"device_id": 619614334,
			"focus": null,
			"allow_shared": false,
			"device_model": "",
			"association_space_id": "5d702aee693b38df7a42b3b31412d546",
			"scene_name": ["安全管理-人行动线1", "环境管理-主绿化带"],
			"scene_id": ["e32eec68c6fc4797", "200b155172724509"]
		}],
		"count": 1
	}
}

1.2、修改设备信息

接口描述

应用于对视频设备的特有的属性进行编辑维护

请求方式

POST

请求地址

/v3/service/video-surveillance//project/product/{product_id}/devices

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

path参数

名称	必填	类型	备注
product_id	是	String	产品ID

body请求参数

名称	必填	类型	备注
device_ids	true	List	设备ID集合
allow_shared	true	boolean	是否可以分享设备信息

请求示例：

{
     "device_ids": [111,222],
     "allow_shared": false
}

返回参数说明

名称	必填	类型	备注
code	true	String	错误码
data	false	object
data.id	false	String	主键ID
data.product_id	false	String	产品ID
data.allow_shared	false	boolean	是否可以分享设备信息
msg	true	String	错误信息
status	true	integer	响应状态码

{
	"code":"000000",
	"data":{
        "id":"xxx",
        "product_id":"xxx",
        "allow_shared":false
	},
	"status":200,
	"msg":请求成功
}

1.3、导出视频设备列表

接口描述

应用于对视频设备列表的导出

请求方式

GET

请求地址

/v3/service/video-surveillance/project/{project_id}/devices

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

path参数

名称	必填	类型	备注
project_id	true	String	项目ID

请求示例：

GET /v3/service/video-surveillance/project/XXXXX/devices

返回参数说明

名称	必填	类型	备注
code	true	String	错误码
data	false	object
data.download_url	false	String	导出的csv文件资源地址
data.id	false	String	文件ID
msg	true	String	错误信息
status	true	integer	响应状态码

data返回示例：

{
    "response_time": "2021-10-15T01:35:07.139Z",
    "code": "000000",
    "status": "200",
    "msg": "请求成功",
    "data": {
        "download_url": "http://xlink.oss-cn-hangzhou.aliyuncs.com/xxxx/xxxx.csv",
        "id": "xxxx"
    }
}

错误码

错误码	描述
4001001	导出失败

1.4、批量添加视频设备信息

接口描述

批量添加视频设备信息，应用于对视频设备列表的视频设备添加

请求方式

POST

请求地址

/v3/service/video-surveillance/project/{project_id}/video_device_infos

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

path请求参数

名称	必填	类型	备注
project_id	true	string	项目id

body请求参数

名称	必填	类型	备注
product_id	true	string	产品ID
product_name	true	string	产品名称
device_code	true	string	设备编码
name	true	string	设备名称
brand	false	string	设备品牌
device_type	false	string	string设备型号
macstring	false	string	MAC
sn	false	string	序列号SN
install_address	false	string	安装位置
address	false	string	详细位置
space_id	false	string	空间ID
space_name	false	string	空间名称
supplier	false	string	设备供应商
maintenance_provider	false	string	设备维保单位
maintenance_provider_linkman	false	string	维保联系人
maintenance_provider_phone	false	string	维保联系电话
person_in_charge	false	string	设备负责人
production_data	false	date	出厂日期
scrap_data	false	date	设备报废日期
external_id	false	string	主数据设备ID
camera_type	false	integer	摄像头类型***: 1：普通摄像机（默认）；2：人脸分析机；3：行为分析机； 4：鹰眼摄像机； 5：球机；6：枪机
camera_resolution_ratio	false	string	摄像头分辨率
ptz_control	false	string	是否可云台控制
success	false	boolean	success
errmsg	false	string	导入错误信息报告
errcode	false	integer	错误码
status	false	string	设备状态，0：正常，1：闲置，2：报废
area_name	false	string	区域名称
building_name	false	string	楼栋名称
unit_name	false	string	单元名称
house_name	false	string	房屋名称
source_system	false	string	来源
scene_id	false	string[]	管理场景id
scene_name	false	string[]	管理场景name
device_id	false	integer	设备ID
device_ids	false	integer[]	设备IDs
device_model	false	string	设备型号
allow_shared	false	boolean	允许分享

请求示例：

Content
[
  {
    "corp_id": "string",
    "create_date": "2019-11-04T07:03:48.514Z",
    "create_man": "string",
    "deleted": false,
    "id": "string",
    "product_id": "string",
    "project_id": "string",
    "update_date": "2019-11-04T07:03:48.514Z",
    "update_man": "string",
    "product_name": "string",
    "mac": "string",
    "name": "string",
    "sn": "string",
    "install_address": "string",
    "address": "string",
    "space_id": "string",
    "space_name": "string",
    "brand": "string",
    "supplier": "string",
    "maintenance_provider": "string",
    "maintenance_provider_linkman": "string",
    "maintenance_provider_phone": "string",
    "person_in_charge": "string",
    "scrap_data": "string",
    "device_code": "string",
    "production_data": "string",
    "external_id": "string",
    "camera_type": "string",
    "camera_resolution_ratio": "string",
    "ptz_control": "string",
    "success": true,
    "errmsg": "string",
    "errcode": 0,
    "area_name": "string",
    "building_name": "string",
    "unit_name": "string",
    "house_name": "string",
    "source_system": "string",
    "device_id": 0
}
]

错误码

错误码	描述
4001001	导入不能为空
4001001	单次最多允许导入1000个设备
500001	导入失败

返回参数说明

名称	必填	类型	备注
code	true	string	错误码
data	true	boolean
data.count	true	integer	导入数量
data.succeedSize	true	integer	导入成功数量
data.ImportFailureSize	true	integer	导入失败数量
data.download_url	true	string	CSV 下载地址
data.ImportFailureData	true	object	导入失败数据
msg	true	string	错误信息
status	true	integer	响应状态码

data返回示例：

{   
	"code":"0",   
	"data"：{
		"count":integer,
		"succeedSize":integer,
		"ImportFailureSize":integer,
		"download_url":"",
		"ImportFailureData":{}
	},  
	"msg":"请求成功",   
	"status":200  
}

1.5、设备批量关联项目

接口描述

设备批量关联项目，应用于关联视频设备进入视频视频列表中

请求方式

PUT

请求地址

/v3/service/video-surveillance/project/{project_id}/devices

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

path请求参数

名称	必填	类型	备注
project_id	true	string	项目id

body请求参数

名称	必填	类型	备注
device_id	true	integer	设备id
camera_type	false	integer	摄像头类型: 1：普通摄像机（默认）；2：人脸分析机；3：行为分析机； 4：鹰眼摄像机； 5：球机；6：枪机
camera_resolution_ratio	false	string	摄像头分辨率
ptz_control	true	boolean	是否可云台控制

请求示例：

Content
[
    {
        "device_id": 92228882,
        "camera_type": 1,
        "camera_resolution_ratio": 123,
        "ptz_control": false
    },
    {
        "device_id": 92221113,
        "camera_type": 2,
        "camera_resolution_ratio": 24,
        "ptz_control": true
    }
]

错误码

错误码	描述
4001001	数据为空
4001001	编辑失败
4001001	参数不合法

返回参数说明

名称	必填	类型	备注
code	true	string	错误码
msg	true	string	错误信息
status	true	integer	响应状态码

data返回示例：

{
  "response_time": "2019-11-03T10:34:45.894Z",
  "code": "000000",
  "status": "200",
  "msg": "请求成功"
}

1.6、删除设备

接口描述

删除设备,应用于删除视频设备列表的视频设备

请求方式

DELETE

请求地址

/v3/service/video-surveillance/corp/product/{product_id}/video_device_info/device/{device_id}

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

path请求参数

名称	必填	类型	备注
product_id	true	string	产品id
device_id	true	integer	设备id

返回参数说明

名称	必填	类型	备注
code	true	string	错误码
data	true	boolean	是否成功
msg	true	string	错误信息
status	true	integer	响应状态码

data返回示例：

{   
	"code":"200",   
	"data"：boolean,  
	"msg":"请求成功",   
	"status":200  
}

错误码

错误码	描述
4001001	设备ID不能为空

上次更新：2024-05-09